<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-type" content="text/html; charset=iso-8859-1">
<title>Java-to-Schema Examples - The Java EE 5 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2008-10-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/j5eetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnafd.html">4.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnagx.html">5.&nbsp;&nbsp;JavaServer Pages Technology</a></p>
<p class="toc level2"><a href="bnajo.html">6.&nbsp;&nbsp;JavaServer Pages Documents</a></p>
<p class="toc level2"><a href="bnakc.html">7.&nbsp;&nbsp;JavaServer Pages Standard Tag Library</a></p>
<p class="toc level2"><a href="bnalj.html">8.&nbsp;&nbsp;Custom Tags in JSP Pages</a></p>
<p class="toc level2"><a href="bnaon.html">9.&nbsp;&nbsp;Scripting in JSP Pages</a></p>
<p class="toc level2"><a href="bnaph.html">10.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnaqz.html">11.&nbsp;&nbsp;Using JavaServer Faces Technology in JSP Pages</a></p>
<p class="toc level2"><a href="bnatx.html">12.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnavg.html">13.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnawo.html">14.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="bnaxu.html">15.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">16.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="bnazf.html">17.&nbsp;&nbsp;Binding between XML Schema and Java Classes</a></p>
<p class="toc level3"><a href="bnazg.html">JAXB Architecture</a></p>
<p class="toc level4"><a href="bnazg.html#bnazh">Architectural Overview</a></p>
<p class="toc level4"><a href="bnazg.html#bnazj">The JAXB Binding Process</a></p>
<p class="toc level4"><a href="bnazg.html#bnazl">More about Unmarshalling</a></p>
<p class="toc level4"><a href="bnazg.html#bnazm">More about Marshalling</a></p>
<p class="toc level4"><a href="bnazg.html#bnazn">More about Validation</a></p>
<p class="toc level3 tocsp"><a href="bnazo.html">Representing XML Content</a></p>
<p class="toc level4"><a href="bnazo.html#bnazp">Java Representation of XML Schema</a></p>
<p class="toc level3 tocsp"><a href="bnazq.html">Binding XML Schemas</a></p>
<p class="toc level4"><a href="bnazq.html#bnazr">Simple Type Definitions</a></p>
<p class="toc level4"><a href="bnazq.html#bnazs">Default Data Type Bindings</a></p>
<p class="toc level5"><a href="bnazq.html#bnazt">Schema-to-Java Mapping</a></p>
<p class="toc level5"><a href="bnazq.html#bnazv"><tt>JAXBElement</tt> Object</a></p>
<p class="toc level5"><a href="bnazq.html#bnazw">Java-to-Schema Mapping</a></p>
<p class="toc level3 tocsp"><a href="bnazy.html">Customizing Generated Classes and Java Program Elements</a></p>
<p class="toc level4"><a href="bnazy.html#bnazz">Schema-to-Java</a></p>
<p class="toc level4"><a href="bnazy.html#bnbaa">Java-to-Schema</a></p>
<p class="toc level3 tocsp"><a href="bnbah.html">JAXB Examples</a></p>
<p class="toc level4"><a href="bnbah.html#bnbal">JAXB Compiler Options</a></p>
<p class="toc level4"><a href="bnbah.html#bnban">JAXB Schema Generator Option</a></p>
<p class="toc level4"><a href="bnbah.html#bnbao">About the Schema-to-Java Bindings</a></p>
<p class="toc level4"><a href="bnbah.html#bnbar">Schema-Derived JAXB Classes</a></p>
<p class="toc level5"><a href="bnbah.html#bnbas"><tt>Comment</tt> Class</a></p>
<p class="toc level5"><a href="bnbah.html#bnbat"><tt>Items</tt> Class</a></p>
<p class="toc level5"><a href="bnbah.html#bnbau"><tt>ObjectFactory</tt> Class</a></p>
<p class="toc level5"><a href="bnbah.html#bnbav"><tt>PurchaseOrder</tt> Class</a></p>
<p class="toc level5"><a href="bnbah.html#bnbaw"><tt>PurchaseOrderType</tt> Class</a></p>
<p class="toc level5"><a href="bnbah.html#bnbax"><tt>USAddress</tt> Class</a></p>
<p class="toc level3 tocsp"><a href="bnbay.html">Basic JAXB Examples</a></p>
<p class="toc level4"><a href="bnbay.html#bnbaz">Modify Marshal Example</a></p>
<p class="toc level5"><a href="bnbay.html#bnbba">Building and Running the Modify Marshal Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbay.html#bnbbb">Building and Running the Modify Marshal Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="bnbay.html#bnbbc">Unmarshal Validate Example</a></p>
<p class="toc level5"><a href="bnbay.html#bnbbd">Building and Running the Unmarshal Validate Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbay.html#bnbbe">Building and Running the Unmarshal Validate Example Using Ant</a></p>
<p class="toc level3 tocsp"><a href="bnbbf.html">Customizing JAXB Bindings</a></p>
<p class="toc level4"><a href="bnbbf.html#bnbbg">Why Customize?</a></p>
<p class="toc level4"><a href="bnbbf.html#bnbbh">Customization Overview</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbbi">Inline and External Customizations</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbbo">Scope, Inheritance, and Precedence</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbbq">Customization Syntax</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbby">Customization Namespace Prefix</a></p>
<p class="toc level4 tocsp"><a href="bnbbf.html#bnbbz">Customize Inline Example</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbca">Building and Running the Customize Inline Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbcb">Building and Running the Customize Inline Example Using Ant</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbcc">Customized Schema</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbcd">Global Binding Declarations</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbce">Schema Binding Declarations</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbcf">Class Binding Declarations</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbcg">Property Binding Declarations</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbch"><tt>MyDatatypeConverter</tt> Class</a></p>
<p class="toc level4 tocsp"><a href="bnbbf.html#bnbci">Datatype Converter Example</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbcj">Building and Running the Datatype Converter Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbck">Building and Running the Datatype Converter Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="bnbbf.html#bnbcl">Binding Declaration Files</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbcm">JAXB Version, Namespace, and Schema Attributes</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbcq">Global and Schema Binding Declarations</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbcr">Class Declarations</a></p>
<p class="toc level4 tocsp"><a href="bnbbf.html#bnbcs">External Customize Example</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbct">Building and Running the External Customize Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbbf.html#bnbcu">Building and Running the External Customize Example Using Ant</a></p>
<div class="onpage">
<p class="toc level3 tocsp"><a href="">Java-to-Schema Examples</a></p>
<p class="toc level4"><a href="#bnbcw">Create Marshal Example</a></p>
<p class="toc level5"><a href="#bnbcx">Building and Running the Create Marshal Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="#bnbcy">Building and Running the Create Marshal Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="#bnbcz">XmlAccessorOrder Example</a></p>
<p class="toc level5"><a href="#bnbda">Using the <tt>@XmlAccessorOrder</tt> Annotation to Define Schema Element Ordering</a></p>
<p class="toc level5"><a href="#bnbdb">Using the <tt>@XmlType</tt> Annotation to Define Schema Element Ordering</a></p>
<p class="toc level5"><a href="#bnbdc">Schema Content Ordering in the Example</a></p>
<p class="toc level5"><a href="#bnbdd">Building and Running the XmlAccessorOrder Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="#bnbde">Building and Running the XmlAccessorOrder Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="#bnbdf">XmlAdapter Field Example</a></p>
<p class="toc level5"><a href="#bnbdg">Building and Running the XmlAdapter Field Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="#bnbdh">Building and Running the XmlAdapter Field Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="#bnbdi">XmlAttribute Field Example</a></p>
<p class="toc level5"><a href="#bnbdj">Building and Running the XmlAttribute Field Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="#bnbdk">Building and Running the XmlAttribute Field Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="#bnbdl">XmlRootElement Example</a></p>
<p class="toc level5"><a href="#bnbdm">Building and Running the XmlRootElement Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="#bnbdn">Building and Running the XmlRootElement Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="#bnbdo">XmlSchemaType Class Example</a></p>
<p class="toc level5"><a href="#bnbdp">Building and Running the XmlSchemaType Class Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="#bnbdq">Building and Running the XmlSchemaType Class Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="#bnbdr">XmlType Example</a></p>
<p class="toc level5"><a href="#bnbds">Building and Running the XmlType Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="#bnbdt">Building and Running the XmlType Example Using Ant</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnbdu.html">Further Information about JAXB</a></p>
<p class="toc level2 tocsp"><a href="bnbdv.html">18.&nbsp;&nbsp;Streaming API for XML</a></p>
<p class="toc level2"><a href="bnbhf.html">19.&nbsp;&nbsp;SOAP with Attachments API for Java</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbls.html">20.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbnb.html">21.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="bnboc.html">22.&nbsp;&nbsp;Session Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">23.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;V&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">24.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="bnbrl.html">25.&nbsp;&nbsp;Persistence in the Web Tier</a></p>
<p class="toc level2"><a href="bnbrs.html">26.&nbsp;&nbsp;Persistence in the EJB Tier</a></p>
<p class="toc level2"><a href="bnbtg.html">27.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level1 tocsp"><a href="bnbwi.html">Part&nbsp;VI&nbsp;Services</a></p>
<p class="toc level2"><a href="bnbwj.html">28.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bnbyk.html">29.&nbsp;&nbsp;Securing Java EE Applications</a></p>
<p class="toc level2"><a href="bncas.html">30.&nbsp;&nbsp;Securing Web Applications</a></p>
<p class="toc level2"><a href="bncdq.html">31.&nbsp;&nbsp;The Java Message Service API</a></p>
<p class="toc level2"><a href="bncgv.html">32.&nbsp;&nbsp;Java EE Examples Using the JMS API</a></p>
<p class="toc level2"><a href="bncih.html">33.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">34.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncjx.html">35.&nbsp;&nbsp;Connector Architecture</a></p>
<p class="toc level1 tocsp"><a href="bnckn.html">Part&nbsp;VII&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="bncko.html">36.&nbsp;&nbsp;The Coffee Break Application</a></p>
<p class="toc level2"><a href="bnclz.html">37.&nbsp;&nbsp;The Duke's Bank Application</a></p>
<p class="toc level1 tocsp"><a href="gexbq.html">Part&nbsp;VIII&nbsp;Appendixes</a></p>
<p class="toc level2"><a href="bncno.html">A.&nbsp;&nbsp;Java Encoding Schemes</a></p>
<p class="toc level2"><a href="bncnq.html">B.&nbsp;&nbsp;Preparation for Java EE Certification Exams</a></p>
<p class="toc level2"><a href="bncnt.html">C.&nbsp;&nbsp;About the Authors</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td width="705px">
         <div class="header">
             <div class="header-links-top">
                 <a href="http://java.sun.com">java.sun.com</a> |
                 <a href="http://docs.sun.com/">docs.sun.com</a><br>
             </div> 
             <img src="graphics/tutorialBanner.gif" width="704" height="120" alt="The Java&trade; EE 5 Tutorial"/>
             <div class="header-links">
	         <a href="index.html">Home</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/download.html">Download</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/JavaEETutorial.pdf">PDF</a> |
                 <a href="http://java.sun.com/javaee/5/docs/api/index.html">API</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/faq.html">FAQ</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/search.html">Search</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/sendusmail.html">Feedback</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/history.html">History</a>
             </div>
             <div class="navigation">
                 <a href="bnbbf.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
                 <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
                 <a href="bnbdu.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnbcv"></a><h3>Java-to-Schema Examples</h3>
<a name="indexterm-1783"></a><p>The Java-to-Schema examples show how to use annotations to map Java classes to
XML schema.</p><p>If you are using JDK 6, perform the following steps before you
run any of the Java-to-Schema examples:</p>
<ol><li><p>Change to one of the Java-to-Schema example directories (for example, <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/j2s-create-marshal</tt>.</p></li>
<li><p>Run the following Ant command:</p><pre><tt><b>ant update-endorsed</b></tt></pre><p>This command creates an <tt>endorsed</tt> directory in the JDK and copies the <tt>webservices-api.jar</tt> file from the Application Server's <tt>lib/endorsed/</tt> directory into it.</p></li></ol>


<a name="bnbcw"></a><h4>Create Marshal Example</h4>
<a name="indexterm-1784"></a><p>The Create Marshal example illustrates Java-to-schema databinding. It demonstrates marshalling and unmarshalling of
JAXB annotated classes and also shows how to enable JAXP 1.3 validation at
unmarshal time using a schema file that was generated from the JAXB mapped
classes.</p><p>The schema file, <tt>bc.xsd</tt>, was generated with the following commands:</p><pre><tt><b>schemagen src/cardfile/*.java</b></tt>
<tt><b>cp schema1.xsd bc.xsd</b></tt></pre><p>Note that <tt>schema1.xsd</tt>, was copied to <tt>bc.xsd</tt>; <tt>schemagen</tt> does not allow you
to specify a schema name of your choice.</p>

<a name="bnbcx"></a><h5>Building and Running the Create Marshal Example Using NetBeans IDE</h5>
<p>Follow these instructions to build and run the Create Marshal example on your
Application Server instance using the NetBeans IDE.</p>
<ol><li><p>In NetBeans IDE, select File&rarr;Open Project.</p></li>
<li><p>In the Open Project dialog, navigate to <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/</tt>.</p></li>
<li><p>Select the <tt>j2s-create-marshal</tt> folder.</p></li>
<li><p>Select the Open as Main Project check box.</p></li>
<li><p>Click Open Project.</p></li>
<li><p>Right-click the <tt>j2s-create-marshal</tt> project and select Run.</p></li></ol>


<a name="bnbcy"></a><h5>Building and Running the Create Marshal Example Using Ant</h5>
<p>To compile and run the Create Marshal example using Ant, in a
terminal window, go to the <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/j2s-create-marshal/</tt> directory and type the following:</p><pre><tt><b>ant runapp</b></tt></pre>

<a name="bnbcz"></a><h4>XmlAccessorOrder Example</h4>
<a name="indexterm-1785"></a><a name="indexterm-1786"></a><a name="indexterm-1787"></a><a name="indexterm-1788"></a><a name="indexterm-1789"></a><p>The j2s-xmlAccessorOrder example shows how to use the <tt>@XmlAccessorOrder</tt> and <tt>@XmlType.propOrder</tt> annotations
to dictate the order in which XML content is marshalled/unmarshalled by a Java
type.</p><p>With Java-to-schema mapping, a JavaBean&rsquo;s properties and fields are mapped to an XML
Schema type. The class elements are mapped to either an XML Schema complex
type or an XML Schema simple type. The default element order for a
generated schema type is currently unspecified because Java reflection does not impose a
return order. The lack of reliable element ordering negatively impacts application portability. You
can use two annotations, <tt>@XmlAccessorOrder</tt> and <tt>@XmlType.propOrder</tt>, to define schema element ordering for
applications that need to be portable across JAXB Providers.</p>

<a name="bnbda"></a><h5>Using the <tt>@XmlAccessorOrder</tt> Annotation to Define Schema Element Ordering</h5>
<a name="indexterm-1790"></a><p><a name="indexterm-1791"></a><a name="indexterm-1792"></a>The <tt>@XmlAccessorOrder</tt> annotation imposes one of two element ordering algorithms, <tt>AccessorOrder.UNDEFINED</tt> or <tt>AccessorOrder.ALPHABETICAL</tt>.
<tt>AccessorOrder.UNDEFINED</tt> is the default setting. The order is dependent on the system&rsquo;s reflection
implementation. <tt>AccessorOrder.ALPHABETICAL</tt> orders the elements in lexicographic order as determined by <tt>java.lang.String.CompareTo(String anotherString)</tt>.</p><p><a name="indexterm-1793"></a><a name="indexterm-1794"></a>You can define the <tt>@XmlAccessorOrder</tt> annotation for annotation type <tt>ElementType.PACKAGE</tt> on a class
object. When the <tt>@XmlAccessorOrder</tt> annotation is defined on a package, the scope of the
formatting rule is active for every class in the package. When defined on
a class, the rule is active on the contents of that class.</p><p>There can be multiple <tt>@XmlAccessorOrder</tt> annotations within a package. The order of precedence
is the innermost (class) annotation takes precedence over the outer annotation. For example,
if <tt>@XmlAccessorOrder(AccessorOrder.ALPHABETICAL)</tt> is defined on a package and <tt>@XmlAccessorOrder(AccessorOrder.UNDEFINED)</tt> is defined on
a class in that package, the contents of the generated schema type for
the class would be in an unspecified order and the contents of the
generated schema type for every other class in the package would be alphabetical
order.</p>

<a name="bnbdb"></a><h5>Using the <tt>@XmlType</tt> Annotation to Define Schema Element Ordering</h5>
<a name="indexterm-1795"></a><a name="indexterm-1796"></a><a name="indexterm-1797"></a><p>The <tt>@XmlType</tt> annotation can be defined for a class. The annotation element <tt>propOrder()</tt>
in the <tt>@XmlType</tt> annotation allows you to specify the content order in the
generated schema type. When you use the <tt>@XmlType.propOrder</tt> annotation on a class to specify
content order, all public properties and public fields in the class must be
specified in the parameter list. Any public property or field that you want
to keep out of the parameter list must be annotated with <tt>@XmlAttribute</tt>
or <tt>@XmlTransient</tt> annotation.</p><p>The default content order for <tt>@XmlType.propOrder</tt> is <tt>{}</tt> or <tt>{""}</tt>, not active.
In such cases, the active <tt>@XmlAccessorOrder</tt> annotation takes precedence. When class content order
is specified by the <tt>@XmlType.propOrder</tt> annotation, it takes precedence over any active <tt>@XmlAccessorOrder</tt>
annotation on the class or package. If the <tt>@XmlAccessorOrder</tt> and <tt>@XmlType.propOrder(A, B, ...)</tt> annotations are
specified on a class, the <tt>propOrder</tt> always takes precedence regardless of the order of
the annotation statements. For example, in the code below, the <tt>@XmlAccessorOrder</tt> annotation
precedes the <tt>@XmlType.propOrder</tt> annotation.</p><pre>@XmlAccessorOrder(AccessorOrder.ALPHABETICAL)
@XmlType(propOrder={"name", "city"})
public class USAddress {
            .
            .
    public String getCity() {return city;}
    public void setCity(String city) {this.city = city;}
    public String getName() {return name;}
    public void setName(String name) {this.name = name;}
            .
            .
}</pre><p>In the code below, the <tt>@XmlType.propOrder</tt> annotation precedes the <tt>@XmlAccessorOrder</tt> annotation.</p><pre>@XmlType(propOrder={"name", "city"})
@XmlAccessorOrder(AccessorOrder.ALPHABETICAL)
public class USAddress {
            .
            .
    public String getCity() {return city;}
    public void setCity(String city) {this.city = city;}
    public String getName() {return name;}
    public void setName(String name) {this.name = name;}
            .
            .
}</pre><p>In both scenarios, <tt>propOrder</tt> takes precedence and the identical schema content shown below
will be generated.</p><pre>&lt;xs:complexType name="usAddress">
   &lt;xs:sequence>
        &lt;xs:element name="name" type="xs:string" minOccurs="0"/>
        &lt;xs:element name="city" type="xs:string" minOccurs="0"/>
   &lt;/xs:sequence>
&lt;/xs:complexType></pre>

<a name="bnbdc"></a><h5>Schema Content Ordering in the Example</h5>
<a name="indexterm-1798"></a><p>The purchase order code example demonstrates the effects of schema content ordering using
the <tt>@XmlAccessorOrder</tt> annotation at the package and class level, and the <tt>@XmlType.propOrder</tt> annotation on
a class.</p><p>Class <tt>package-info.java</tt> defines <tt>@XmlAccessorOrder</tt> to be <tt>ALPHABETICAL</tt> for the package. The public fields
<tt>shipTo</tt> and <tt>billTo</tt> in class <tt>PurchaseOrderType</tt> will be affected in the generated
schema content order by this rule. Class <tt>USAddress</tt> defines the <tt>@XmlType.propOrder</tt> annotation on
the class. User of this annotation demonstrates user-defined property order superseding <tt>ALPHABETICAL</tt> order
in the generated schema.</p><p>The generated schema file can be found in the <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/j2s-xmlAccessorOrder/build/schemas/</tt> directory.</p>

<a name="bnbdd"></a><h5>Building and Running the XmlAccessorOrder Example Using NetBeans IDE</h5>
<p>Follow these instructions to build and run the XmlAccessorOrder example on your Application
Server instance using the NetBeans IDE.</p>
<ol><li><p>In NetBeans IDE, select File&rarr;Open Project.</p></li>
<li><p>In the Open Project dialog, navigate to <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/</tt>.</p></li>
<li><p>Select the <tt>j2s-xmlAccessorOrder</tt> folder.</p></li>
<li><p>Select the Open as Main Project check box.</p></li>
<li><p>Click Open Project.</p></li>
<li><p>Right-click the <tt>j2s-xmlAccessorOrder</tt> project and select Run.</p></li></ol>


<a name="bnbde"></a><h5>Building and Running the XmlAccessorOrder Example Using Ant</h5>
<p>To compile and run the XmlAccessorOrder example using Ant, in a terminal window,
go to the <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/j2s-xmlAccessorOrder/</tt> directory and type the following:</p><pre><tt><b>ant runapp</b></tt></pre>

<a name="bnbdf"></a><h4>XmlAdapter Field Example</h4>
<a name="indexterm-1799"></a><a name="indexterm-1800"></a><a name="indexterm-1801"></a><a name="indexterm-1802"></a><p>The XmlAdapter Field example demonstrates how to use the <tt>XmlAdapter</tt> interface and
the <tt>@XmlJavaTypeAdapter</tt> annotation to provide a custom mapping of XML content into and
out of a <tt>HashMap</tt> (field) that uses an <tt>int</tt> as the key and
a <tt>String</tt> as the value.</p><p><a name="indexterm-1803"></a><a name="indexterm-1804"></a><a name="indexterm-1805"></a>Interface <tt>XmlAdapter</tt> and annotation <tt>@XmlJavaTypeAdapter</tt> are used for special processing of data types during
unmarshalling/marshalling. There are a variety of XML data types for which the representation
does not map easily into Java (for example, <tt>xs:DateTime</tt> and <tt>xs:Duration</tt>), and Java types
which do not map conveniently into XML representations, for example implementations of <tt>java.util.Collection</tt>
(such as <tt>List</tt>) and <tt>java.util.Map</tt> (such as <tt>HashMap</tt>) or for non-JavaBean classes.</p><p>The <tt>XmlAdapter</tt> interface and the <tt>@XmlJavaTypeAdapter</tt> annotation are provided for cases such
as these. This combination provides a portable mechanism for reading/writing XML content into
and out of Java applications.</p><p><a name="indexterm-1806"></a>The <tt>XmlAdapter</tt> interface defines the methods for data reading/writing.</p><pre>/*
 *  ValueType - Java class that provides an XML representation
 *              of the data. It is the object that is used for
 *              marshalling and unmarshalling.
 *
 *  BoundType - Java class that is used to process XML content.
 */
public abstract class XmlAdapter&lt;ValueType,BoundType> {
    // Do-nothing constructor for the derived classes.
    protected XmlAdapter() {}
    // Convert a value type to a bound type.
    public abstract BoundType unmarshal(ValueType v);
    // Convert a bound type to a value type.
    public abstract ValueType marshal(BoundType v);
 }</pre><p><a name="indexterm-1807"></a>You can use the <tt>@XmlJavaTypeAdapter</tt> annotation to associate a particular <tt>XmlAdapter</tt> implementation with
a <tt>Target</tt> type, <tt>PACKAGE</tt>, <tt>FIELD</tt>, <tt>METHOD</tt>, <tt>TYPE</tt>, or <tt>PARAMETER</tt>.</p><p><a name="indexterm-1808"></a>The XmlAdapter Field example shows how to use an <tt>XmlAdapter</tt> for mapping XML
content into and out of a (custom) <tt>HashMap</tt>. The <tt>HashMap</tt> object, <tt>basket</tt>, in
class <tt>KitchenWorldBasket</tt>, uses a key of type <tt>int</tt> and a value of type
<tt>String</tt>. These data types should be reflected in the XML content that is
read and written, so the XML content should look like this.</p><pre>&lt;basket>
     &lt;entry key="9027">glasstop stove in black&lt;/entry>
     &lt;entry key="288">wooden spoon&lt;/entry>
&lt;/basket></pre><p>The default schema generated for Java type <tt>HashMap</tt> does not reflect the desired
format.</p><pre>&lt;xs:element name="basket">
   &lt;xs:complexType>
     &lt;xs:sequence>
       &lt;xs:element name="entry" minOccurs="0" maxOccurs="unbounded">
         &lt;xs:complexType>
           &lt;xs:sequence>
             &lt;xs:element name="key" minOccurs="0" type="xs:anyType"/>
             &lt;xs:element name="value" minOccurs="0" type="xs:anyType"/>
          &lt;/xs:sequence>
        &lt;/xs:complexType>
      &lt;/xs:element>
    &lt;/xs:sequence>
  &lt;/xs:complexType>
&lt;/xs:element></pre><p>In the default <tt>HashMap</tt> schema, key and value are both elements and are
of data type <tt>anyType</tt>. The XML content will look like this:</p><pre>&lt;basket>
     &lt;entry>
        &lt;key>9027&lt;/>
        &lt;value>glasstop stove in black&lt;/>
     &lt;/entry>
     &lt;entry>
        &lt;key>288&lt;/>
        &lt;value>wooden spoon&lt;/>
    &lt;/entry>
&lt;/basket></pre><p>To resolve this issue, the example uses two Java classes, <tt>PurchaseList</tt> and
<tt>PartEntry</tt>, that reflect the needed schema format for unmarshalling/marshalling the content. The XML
schema generated for these classes is as follows:</p><pre>&lt;xs:complexType name="PurchaseListType">
    &lt;xs:sequence>
        &lt;xs:element name="entry" type="partEntry"
            nillable="true" maxOccurs="unbounded"
            minOccurs="0"/>
    &lt;/xs:sequence>
&lt;/xs:complexType>
&lt;xs:complexType name="partEntry">
    &lt;xs:simpleContent>
        &lt;xs:extension base="xs:string">
            &lt;xs:attribute name="key" type="xs:int"
                use="required"/>
        &lt;/xs:extension>
    &lt;/xs:simpleContent>
&lt;/xs:complexType></pre><p>Class <tt>AdapterPurchaseListToHashMap</tt> implements the <tt>XmlAdapter</tt> interface. In class <tt>KitchenWorldBasket</tt>, the <tt>@XmlJavaTypeAdapter</tt> annotation is
used to pair <tt>AdapterPurchaseListToHashMap</tt> with field <tt>HashMap</tt> <tt>basket</tt>. This pairing will cause the
marshal/unmarshal method of <tt>AdapterPurchaseListToHashMap</tt> to be called for any corresponding marshal/unmarshal action
on <tt>KitchenWorldBasket</tt>.</p>

<a name="bnbdg"></a><h5>Building and Running the XmlAdapter Field Example Using NetBeans IDE</h5>
<p>Follow these instructions to build and run the XmlAdapter Field example on your
Application Server instance using the NetBeans IDE.</p>
<ol><li><p>In NetBeans IDE, select File&rarr;Open Project.</p></li>
<li><p>In the Open Project dialog, navigate to <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/</tt>.</p></li>
<li><p>Select the <tt>j2s-xmlAdapter-field</tt> folder.</p></li>
<li><p>Select the Open as Main Project check box.</p></li>
<li><p>Click Open Project.</p></li>
<li><p>Right-click the <tt>j2s-xmlAdapter-field</tt> project and select Run.</p></li></ol>


<a name="bnbdh"></a><h5>Building and Running the XmlAdapter Field Example Using Ant</h5>
<p>To compile and run the XmlAdapter Field example using Ant, in a
terminal window, go to the <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/j2s-xmlAdapter-field/</tt> directory and type the following:</p><pre><tt><b>ant runapp</b></tt></pre>

<a name="bnbdi"></a><h4>XmlAttribute Field Example</h4>
<a name="indexterm-1809"></a><a name="indexterm-1810"></a><a name="indexterm-1811"></a><a name="indexterm-1812"></a><p>The XmlAttribute Field example shows how to use the <tt>@XmlAttribute</tt> annotation to define
a property or field to be treated as an XML attribute.</p><p>The <tt>@XmlAttribute</tt> annotation maps a field or JavaBean property to an XML attribute.
The following rules are imposed:</p>
<ul><li><p>A static final field is mapped to a XML fixed attribute.</p></li>
<li><p>When the field or property is a collection type, the items of the collection type must map to a schema simple type.</p></li>
<li><p>When the field or property is other than a collection type, the type must map to a schema simple type.</p></li></ul>
<p>When following the JavaBean programming paradigm, a property is defined by a <tt>get</tt>
and <tt>set</tt> prefix on a field name.</p><pre>int zip;
public int getZip(){return zip;}
public void setZip(int z){zip=z;}</pre><p>Within a bean class, you have the choice of setting the <tt>@XmlAttribute</tt>
annotation on one of three components: the field, the setter method, or the
getter method. If you set the <a name="indexterm-1813"></a><tt>@XmlAttribute</tt> annotation on the field, the
setter method will need to be renamed or there will be a naming
conflict at compile time. If you set the <tt>@XmlAttribute</tt> annotation on one
of the methods, it must be set on either the setter or getter
method, but not on both.</p><p>The XmlAttribute Field example shows how to use the <tt>@XmlAttribute</tt> annotation on a
static final field, on a field rather than on one of the
corresponding bean methods, on a bean property (method), and on a field that
is other than a collection type. In class <tt>USAddress</tt>, fields, country, and zip are
tagged as attributes. The <tt>setZip</tt> method was disabled to avoid the compile error.
Property state was tagged as an attribute on the setter method. You could
have used the getter method instead. In class <tt>PurchaseOrderType</tt>, field <tt>cCardVendor</tt> is
a non-collection type. It meets the requirement of being a simple type; it
is an <tt>enum</tt> type.</p>

<a name="bnbdj"></a><h5>Building and Running the XmlAttribute Field Example Using NetBeans IDE</h5>
<p>Follow these instructions to build and run the XmlAttribute Field example on your
Application Server instance using the NetBeans IDE.</p>
<ol><li><p>In NetBeans IDE, select File&rarr;Open Project.</p></li>
<li><p>In the Open Project dialog, navigate to <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/</tt>.</p></li>
<li><p>Select the <tt>j2s-xmlAttribute-field</tt> folder.</p></li>
<li><p>Select the Open as Main Project check box.</p></li>
<li><p>Click Open Project.</p></li>
<li><p>Right-click the <tt>j2s-xmlAttribute-field</tt> project and select Run.</p></li></ol>


<a name="bnbdk"></a><h5>Building and Running the XmlAttribute Field Example Using Ant</h5>
<p>To compile and run the XmlAttribute Field example using Ant, in a
terminal window, go to the <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/j2s-xmlAttribute-field/</tt> directory and type the following:</p><pre><tt><b>ant runapp</b></tt></pre>

<a name="bnbdl"></a><h4>XmlRootElement Example</h4>
<a name="indexterm-1814"></a><a name="indexterm-1815"></a><a name="indexterm-1816"></a><p>The XmlRootElement example demonstrates the use of the <tt>@XmlRootElement</tt> annotation to define
an XML element name for the XML schema type of the corresponding class.</p><p>The <tt>@XmlRootElement</tt> annotation maps a class or an <tt>enum</tt> type to an
XML element. At least one element definition is needed for each top-level Java
type used for unmarshalling/marshalling. If there is no element definition, there is no
starting location for XML content processing.</p><p>The <tt>@XmlRootElement</tt> annotation uses the class name as the default element name. You
can change the default name by using the annotation attribute <tt>name</tt>. If you
do, the specified name will then be used as the element name and
the type name. It is common schema practice for the element and type
names to be different. You can use the <tt>@XmlType</tt> annotation to set
the element type name.</p><p>The namespace attribute of the <tt>@XmlRootElement</tt> annotation is used to define a namespace
for the element.</p>

<a name="bnbdm"></a><h5>Building and Running the XmlRootElement Example Using NetBeans IDE</h5>
<p>Follow these instructions to build and run the XmlRootElement example on your Application
Server instance using the NetBeans IDE.</p>
<ol><li><p>In NetBeans IDE, select File&rarr;Open Project.</p></li>
<li><p>In the Open Project dialog, navigate to <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/</tt>.</p></li>
<li><p>Select the <tt>j2s-xmlRootElement</tt> folder.</p></li>
<li><p>Select the Open as Main Project check box.</p></li>
<li><p>Click Open Project.</p></li>
<li><p>Right-click the <tt>j2s-xmlRootElement</tt> project and select Run.</p></li></ol>


<a name="bnbdn"></a><h5>Building and Running the XmlRootElement Example Using Ant</h5>
<p>To compile and run the XmlRootElement example using Ant, in a terminal window,
go to the <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/j2s-xmlRootElement/</tt> directory and type the following:</p><pre><tt><b>ant runapp</b></tt></pre>

<a name="bnbdo"></a><h4>XmlSchemaType Class Example</h4>
<a name="indexterm-1817"></a><a name="indexterm-1818"></a><a name="indexterm-1819"></a><a name="indexterm-1820"></a><a name="indexterm-1821"></a><p>The XmlSchemaType Class example demonstrates the use of the annotation <tt>@XmlSchemaType</tt> to
customize the mapping of a property or field to an XML built-in type.</p><p>The <tt>@XmlSchemaType</tt> annotation can be used to map a Java type to one
of the XML built-in types. This annotation is most useful in mapping a
Java type to one of the nine date/time primitive data types.</p><p>When the <tt>@XmlSchemaType</tt> annotation is defined at the package level, the identification requires
both the XML built-in type name and the corresponding Java type class. An
<tt>@XmlSchemaType</tt> definition on a field or property takes precedence over a package definition.</p><p>The XmlSchemaType Class example shows how to use the <tt>@XmlSchemaType</tt> annotation at
the package level, on a field, and on a property. File <tt>TrackingOrder</tt> has
two fields, <tt>orderDate</tt> and <tt>deliveryDate</tt>, which are defined to be of type
<tt>XMLGregorianCalendar</tt>. The generated schema will define these elements to be of XML
built-in type <tt>gMonthDay</tt>. This relationship was defined on the package in the file <tt>package-info.java</tt>.
Field <tt>shipDate</tt> in file <tt>TrackingOrder</tt> is also defined to be of type <tt>XMLGregorianCalendar</tt>,
but the <tt>@XmlSchemaType</tt> annotation statements override the package definition and specify the field
to be of type <tt>date</tt>. Property method <tt>getTrackingDuration</tt> defines the schema element to
be defined as primitive type <tt>duration</tt> and not Java type <tt>String</tt>.</p>

<a name="bnbdp"></a><h5>Building and Running the XmlSchemaType Class Example Using NetBeans IDE</h5>
<p>Follow these instructions to build and run the XmlSchemaType Class example on your
Application Server instance using the NetBeans IDE.</p>
<ol><li><p>In NetBeans IDE, select File&rarr;Open Project.</p></li>
<li><p>In the Open Project dialog, navigate to <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/</tt>.</p></li>
<li><p>Select the <tt>j2s-xmlSchemaType-class</tt> folder.</p></li>
<li><p>Select the Open as Main Project check box.</p></li>
<li><p>Click Open Project.</p></li>
<li><p>Right-click the <tt>j2s-xmlSchemaType-class</tt> project and select Run.</p></li></ol>


<a name="bnbdq"></a><h5>Building and Running the XmlSchemaType Class Example Using Ant</h5>
<p>To compile and run the XmlSchemaType Class example using Ant, in a
terminal window, go to the <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/j2s-xmlSchemaType-class/</tt> directory and type the following:</p><pre><tt><b>ant runapp</b></tt></pre>

<a name="bnbdr"></a><h4>XmlType Example</h4>
<a name="indexterm-1822"></a><a name="indexterm-1823"></a><a name="indexterm-1824"></a><p>The XmlType example demonstrates the use of the <tt>@XmlType</tt> annotation. The <tt>@XmlType</tt> annotation
maps a class or an <tt>enum</tt> type to a XML Schema type.</p><p>A class must have either a public zero-argument constructor or a static zero-argument
factory method in order to be mapped by this annotation. One of these
methods is used during unmarshalling to create an instance of the class. The
factory method may reside within in a factory class or the existing class.
</p><p>There is an order of precedence as to which method is used
for unmarshalling:</p>
<ul><li><p>If a factory class is identified in the annotation, a corresponding factory method in that class must also be identified and that method will be used.</p></li>
<li><p>If a factory method is identified in the annotation but no factory class is identified, the factory method must reside in the current class. The factory method is used even if there is a public zero arg constructor method present.</p></li>
<li><p>If no factory method is identified in the annotation, the class must contain a public zero arg constructor method.</p></li></ul>
<p>In this example, a factory class provides zero arg factory methods for several
classes. The <tt>@XmlType</tt> annotation on class <tt>OrderContext</tt> references the factory class. The
unmarshaller will use the identified factory method in this class.</p><pre>public class OrderFormsFactory {
    public OrderContext newOrderInstance() {
        return new OrderContext()
    }
    public PurchaseOrderType newPurchaseOrderType() {
        return new newPurchaseOrderType();
    }
}
@XmlType(name="oContext", factoryClass="OrderFormsFactory",
  factoryMethod="newOrderInstance")
public class OrderContext {
    public OrderContext(){ ..... }
}</pre><p>In this example, a factory method is defined in a class, which
also contains a standard class construct. Because the <tt>factoryMethod</tt> value is defined and no
<tt>factoryClass</tt> is defined, the factory method <tt>newOrderInstance</tt> is used during unmarshalling.</p><pre>@XmlType(name="oContext", factoryMethod="newOrderInstance")
 public class OrderContext {
    public OrderContext(){ ..... }
    public OrderContext newOrderInstance() {
         return new OrderContext();
    }
}</pre>

<a name="bnbds"></a><h5>Building and Running the XmlType Example Using NetBeans IDE</h5>
<p>Follow these instructions to build and run the XmlType example on your Application
Server instance using the NetBeans IDE.</p>
<ol><li><p>In NetBeans IDE, select File&rarr;Open Project.</p></li>
<li><p>In the Open Project dialog, navigate to <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/</tt>.</p></li>
<li><p>Select the <tt>j2s-xmlType</tt> folder.</p></li>
<li><p>Select the Open as Main Project check box.</p></li>
<li><p>Click Open Project.</p></li>
<li><p>Right-click the <tt>j2s-xmlType</tt> project and select Run.</p></li></ol>


<a name="bnbdt"></a><h5>Building and Running the XmlType Example Using Ant</h5>
<p>To compile and run the XmlType example using Ant, in a terminal
window, go to the <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/jaxb/j2s-xmlType/</tt> directory and type the following:</p><pre><tt><b>ant runapp</b></tt></pre>
         </div>
         <div class="navigation">
             <a href="bnbbf.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
             <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
             <a href="bnbdu.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
         </div>

         <div class="copyright">
      	    <p>The material in The Java&trade; EE 5 Tutorial is <a href='docinfo.html'>copyright</a>-protected and may not be published in other works without express written permission from Sun Microsystems.</p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

